Key Window                                  (v 1.63)
-=-=-=-=-=-

by Richard G. Hallas

____________________________________________________

This program provides an on-screen function keystrip
in a window. It should prove useful to owners of
all machines later than the A440/1, as the newer
machines do not have keystrip holders on their
keyboards. It does more than that, however: you can
'press' the keys by clicking on them with the mouse,
and Key Window can keep track of a list of up to 32
keystrips, opening and closing them automatically as
you load, use & quit applications.

To use:
-------

Load by double-clicking in the usual way. If you are
in the habit of booting up a number of applications
when you switch on, then you might like to include
Key Window near the beginning of your boot-up
sequence so that it can keep track of other
applications starting up and open keystrips for
them.

Once loaded, clicking SELECT on the icon bar icon
will open a keystrip window; either the first one
on the list, or the last one shown if you closed a
strip which was opened automatically. (If you ignore
Key Window, and load DeskEdit [for example] a
keystrip will appear anyway, since DeskEdit is
defined as one of the applications for which Key
Window has a keystrip.) The keystrip will appear
behind other windows so that it is inobtrusive, but
you can easily bring it to the front by clicking
its title bar in the usual way.

Pressing the hot-key combination <SHIFT-CTRL-TAB>
or <CTRL-SHIFT-INSERT> will toggle the keystrip
between the front and the back of the desktop.
(The hot-key may not work if an application such
as DeskEdit has the input focus; it is for this
reason that there are two version of the same
hot-key.)

In addition to opening and closing keystrips when
you load and quit applications, Key Window is also
'context sensitive', and will update the contents of
the keystrip window according to whichever program
currently owns the caret. If a program which does
not have a keystrip defined claims the caret, then
the keystrip will be closed, but if the caret is
turned off completely, then the last keystrip used
will continue to be shown.

The icon bar menu has the usual 'Info' and 'Quit'
options, along with two others: 'Keystrips' and
'Choices'. The first of these provides access to an
'Applications' submenu, and choosing an application
from this menu will open a keystrip for it.

The other icon bar submenu, 'Choices', governs how
the keystrip window will operate. The options are as
follows:

 'Open at top': If this is ticked, the window will
  always appear at the top of the screen; otherwise
  it will appear just above the icon bar, or
  wherever you put it last.

 'Auto-scroll': This makes the keystrip window
  behave in the same way as the icon bar does when
  it is full; that is, it scrolls sideways
  automatically when the pointer is moved to the
  left- and right-hand edges.

 'Scroll bar': This toggles the horizontal scroll
  bar and size icon; if 'Auto-scroll' is selected,
  then the scroll bar is unnecessary, but you may
  wish to use it to get from one side to the other
  more quickly.

It is not possible to deselect both 'Auto-scroll'
and 'Scroll bar' at the same time, since it would
obviously then be impossible to move from one side
of the keystrip to the other.

 'Fit screen': This option will force the entire
  strip to fit onto the screen. Obviously, since the
  key labels have space for 16 characters, the
  fully-annotated keystrip cannot be fitted on the
  screen (except with very large screen modes
  indeed). If you select this option, the full
  window will cease to scroll, and will be sized to
  fit whichever screen mode you are using. Any key
  labels which are wholly visible will be centred in
  their slots as usual, but labels which overflow
  their slots will be justified to the left, so that
  you can at least see how they begin. <F12> and
  <CTRL-SHIFT-F12> are usually automatically given
  the respective labels "Command line" and "Exit
  desktop". In 'Fit screen' mode, these will appear
  as "*CLI" and "Exit", but if you save a strip the
  full labels will be used. If these two keypresses
  are being used for other purposes, and therefore
  have different labels from standard, the new
  labels will not be affected by the 'Fit screen'
  mode.

The last two options are separated from the others
by a dotted line, and they govern the way the
'context switching' aspects of the program work.

 'Sense caret': If this option is selected, the
  keystrip will be fully context sensitive, and as
  the input focus moves between windows, the
  keystrip will change to reflect its position.
  (Note that for the sake of simplicity, the
  program's menu refers to the 'caret' when it
  actually means the 'input focus'; there doesn't
  really have to be a physical caret. A good example
  is of this Draw Plus, which only shows a caret
  when entering text objects; the keystrip
  nevertheless still applies.)

 'Sense apps': If this option is selected, Key
  Window will open and close strips as applications
  are loaded and quit. Since this could potentially
  interfere with the context switching option above,
  then if the 'Sense caret' option is on, the 'Sense
  apps' option will only work if a keystrip is not
  currently in use.

All this makes Key Window sound very complicated,
but you should find it quite easy and natural to
use.

Regardless of the state of these options, whenever
the window is opened, or the screen mode is changed,
it will appear behind the other windows, and will
resize itself to fit the current width of the
screen. The default settings of these options can be
defined by editing the !Run file; see that file for
details, and also later in this !Help file.

On to the keystrip window itself. Clicking any of
the key definitions with SELECT or ADJUST will
'press' that key. If you are not using the 'context
switching' features you should remember that the
same key is pressed regardless of whatever strip is
showing; you may for example have the keystrip for
Edit on the screen, but if you are currently using
Impression, then clicking on <CTRL-F4> will bring up
the Find/Replace box rather than doing an Indent
Block in Edit. This seems obvious, but it's easy to
forget. They're the same keys, regardless of how
they're labelled.

Since <CTRL-SHIFT-F12> is a dangerous keystroke (it
normally exits the desktop), I have made the icon as
difficult to click by accident as possible. To
activate it, you must click on it with both SELECT
and ADJUST simultaneously. (The easiest way of doing
this is probably to hold down SELECT and then click
ADJUST.)

The keystrip window has its own menu so you can edit
the strips and create new ones. The menu options are
as follows; I shall deal with them in turn:

 Edit item: this is context-sensitive, and only
  appears when you click over a key label. Enter the
  contents in the submenu leaf; up to 16 characters
  are allowed for each, even when the strip is
  compressed (you just won't be able to see all the
  text).

 Edit title: this allows you to edit the title of
  the keystrip; the title will be used in the
  keystrip window and in the 'Applications' menu.

 Get strip: this is the same as the 'Keystrips'
  option on the icon bar menu, and updates the
  window with whichever keystrip you choose. Any
  unsaved contents of the keystrip window will be
  lost if you use this option. The only difference
  here is that the keystrip is opened at the front,
  whereas it is opened at the back when you select a
  strip from the icon bar menu. You should note that
  if the 'Sense caret' option is on, then using
  either of these application keystrip menus will
  lose the input focus. If it didn't, then the
  keystrip would change back to the one needed for
  the current application as soon as you had
  selected a different one.

 Clear strip: this blanks the strip to give you a
  fresh start. The two usual functions of F12
  (Command line & Exit desktop) are entered for you
  automatically, but you can delete them if you
  wish. Note that if you are entering a strip in
  'Fit screen' mode, "Command line" and "Exit
  desktop" will be abbreviated to "*CLI" and
  "Exit". However, this is for display purposes
  only, and if you save a strip the full labels will
  be saved in the file (unless, of course, you have
  replaced them with something else).

 Open with?: entering a taskname (as it appears in
  the Task Display window) into this submenu will
  make that strip open and close automatically when
  you use a particular application. Leave the option
  blank if you do not wish this to happen, but
  remember that this will disable the context switch
  facilities for that particular application.

  Caution: some application names contain hard
  spaces. If you appear to have typed the name
  correctly but the keystrip fails to open auto-
  matically, try editing the name to include hard
  spaces instead of normal ones. (Enter a hard space
  by typing <ALT-SPACE> rather than just <SPACE>.)

 Save strip: there are two ways of saving
  keystrips, which you must choose from the submenu
  (clicking on 'Save strip' alone will do nothing).
  Firstly, 'Replace old' will overwrite the existing
  definition with your edited version, so you can
  easily add to a strip or correct it. (This option
  is unavailable if you have used 'Clear strip'.)
  Secondly, 'Create new' will save a totally new
  keystrip and add it to the 'Applications' menu.

Notes on saving new strips
--------------------------

When saving a new strip, the data is saved into a
text file within the 'Data' directory in the
!KeyWindow application directory. If you use the
'Create new' save option, Key Window will save the
file with a numeric filename, starting at number
'0'. If '0' exists, then it uses '1', and so on. If
there are 32 files in the directory, then Key Window
will not allow you to save a new strip, only
overwrite existing ones. When Key Window starts up,
it reads in the contents of all the files in the
'Data' directory, in the order in which they appear
in the directory viewer; this is also the order they
will appear in the 'Applications' menu. If you want
a particular strip to always be first on the
'Applications' list (and therefore be the default
one to use when you click on the icon bar icon) you
should make sure it is the first to appear in the
directory viewer; using the name '!' should ensure
this. It doesn't actually matter what you call the
files; the program just uses numerics for the sake
of simplicity.

If you wish to create your function key files in
DeskEdit, say, and not with Key Window itself, the
file format is as follows:

 The first line is the title of the application
  (max. 20 characters) to appear in the window title
  and 'Applications' menu.

 The second line is either blank or a taskname
  (max. 19 characters - extras ignored) for the
  strip to open automatically.

 The remainder of the file has up to 12 lines, one
  for each key. If a line is blank, that key will
  have no labels. Not all 12 keys need to be
  defined: you use only as many lines as the
  keystrip requires.

  Each line has up to four entries, separated by
  commas: for the key alone, and in conjunction with
  Shift, Ctrl and Ctrl-Shift. You need only enter as
  many labels as necessary, so you can finish a line
  before Ctrl-Shift, for example. Each line should
  therefore contain 0 to 3 commas. Note that if,
  say, a particular key has no function alone, but
  has a function in conjunction with Shift, the
  definition line should start with a comma.

  Note also that although spurious commas are not
  necessary, they do not matter, and indeed if you
  save a definition file from the program, every
  line it produces will contain three commas.

Setting options with <KeyWindow$Flags>
--------------------------------------

Key Window can be made to start up every time with a
certain combination of options already in effect.
You must edit the !Run file in the application
directory to achieve this. Alter the number in the
line 'Set KeyWindow$Flags 51' (The value of 51 is
the default if you omit this line or enter an
illegal value). The variable sets the default state
for the six settings which can be temporarily
toggled on and off in the 'Choices' submenu.

The <KeyWindow$Flags> variable is a decimal number
in the range 0 to 63, which is calculated from the
following set of bits, which mean, when they are
set:

   Bit 0: Always open keystrip at top of screen.
   Bit 1: Scroll strip when pointer reaches edges.
   Bit 2: Show horizontal scroll bar, along with a
          resize icon and a toggle size icon.
   Bit 3: Always size keystrip to fit screen.
   Bit 4: Context sensitive: applications gaining
          the caret will open new strips.
   Bit 5: Load sensitive: applications starting up
          and quitting will open and close strips.

So, for example, if you wanted just 'Open at top',
'Scroll' and 'Fit screen' on by default, you would
use the value 11, since you would be setting bits 0,
1 and 3 of the flags, and 11 is the decimal
equivalent of binary 1011.

Do note that the bits are in descending order:
namely, bit 0 is the one on the right.

Note also that any values with bits one and two both
set to zero are invalid, since they would mean that
both the 'Auto scroll' and the 'Scroll bar' options
were off, and the program will not allow this. The
smallest value you may use is 2, and if you try to
use an illegal value the program will automatically
turn on 'Auto-scroll' for you.

Finally
-------

So there you have it - what I hope is a useful
program! This is FREEWARE SOFTWARE and as such may
be distributed quite freely, just as long as it is
not modified or tampered with in any way, and all
the associated files are kept together unmodified.

The !KeyWindow directory should contain the
following files:

!Boot
!Help  (This file)
!Run
!RunImage
!Sprites
!Sprites22
4Sprites
4Sprites22
5Sprites
5Sprites11
5Sprites22
Data
Icons
Icons5
Icons22
Icons522
Source
StripDefs
Template3D
Templates

The Data sub-directory should contain a selection
of keystrips. You should examine these and delete
any you don't need in your own working copy, but if
you pass this application on, please supply all the
keystrips.

Note that if you don't delete some of the keystrips,
then after you have added only a few more strips for
your own applications, the limit of 32 keystrips
will be reached and Key Window will not let you add
any more.

Various additional strips (as well as copies of the
strips supplied in the Data directory) are available
in the StripDefs directory. Have a look through the
selection provided to see if there are any you need
that aren't included in Data by default, and copy
them in if so.

I hope you like this program and find it useful. If
you do, send me a disc with some PD software on it,
and I'll return your disc with the other PD things
I've written on it, and the latest version of this
program if it has been updated. Remember to let me
know which version number you have, and if you find
any bugs, please TELL ME! I try to support all my
programs, and will correct any bugs I know about.
So please send letters, discs, bug reports,
donations (if you feel one is warranted) and
suggestions (none too rude, please!) to the
following address:

Richard G. Hallas,
31 Skelton Crescent,
Crosland Moor,
Huddersfield,
West Yorkshire,
HD4 5PN
ENGLAND

Version revisions:
-=-=-=-=-=-=-=-=-=-

The following versions have been made available in
the public domain:

Version 1.00: First release version, sent to APDL.
This was only sensitive to applications loading and
quitting, not to the movement of the caret between
windows. Its only option was 'Open at top'.

Version 1.06: this provides the additional hot-key
<CTRL-SHIFT-INSERT> (duplicating <CTRL-SHIFT-TAB>),
since DeskEdit 1.20 now uses <CTRL-SHIFT-TAB> for
one of its own features. The hot-key now toggles the
window between front and back, rather than just
bringing it to the front as in version 1.00.

Version 1.06 also corrects a small bug which caused
the window to reopen upon a mode change or return to
the desktop, when it had previously been closed by
the user.

Clicking on the icon with Adjust does the same as
Select, but also provides a little animation! (This
has always happened, but was undocumented for
version 1.00.) I like these little touches!

Version 1.07: Small cosmetic changes have been made
to the Keystrip menu to bring it in line with normal
RISC OS standards. The two Edit submenus used to
have red borders and no titles, and the Save strip
submenu also used to have no title bar. Thanks to
Mark Moxon of RISC Developments for his comments.

Version 1.12: There are numerous modifications in
this version: the system variable <KeyWindow$Flags>
replaces <KeyWindow$Top> in previous versions, and
provides two more options, 'Auto-scroll' and 'Scroll
bar'. The 'Open at top' option on the main icon bar
menu has been replaced by, and moved onto, a new
'Options' submenu, which also contains the two other
options provided by the <KeyWindow$Flags> variable.

(All the menu items are now at the correct 44 OS
units height, whereas they were previously only 40
units high.)

The Keystrip window itself now behaves more sensibly
in that it can scroll itself when the pointer pushes
up to its edges, in the same way as the icon bar. It
is meant to mimic the icon bar, and will 'sense' the
pointer at a similar horizontal position.

For this reason, the horizontal scroll bar is much
less necessary, and can now be toggled on and off.
In the default state, the program leaves it switched
off, which looks neater and saves a little space on
the desktop.

Key-combination labels have been added to the right
hand edge of the window, and are identical to the
ones at the left.

My thanks must go to Henrik Pedersen for his very
useful and helpful suggestions, some of which are
implemented in version 1.12, notably the 'Auto-
scroll' feature. I can't imagine why I didn't think
of this myself! Other suggestions will have to wait
for a later version, when I have time to think about
them.

Version 1.25: Credit must once again go to Henrik
Pedersen, this time for showing me how to read the
taskname of the application owning the caret. It's
actually very easy to do, but I had managed to miss
it every time I had consulted the PRM! Version 1.25
represents a completely new way of operating for Key
Window, and this is the way I wanted it to work in
the first instance. The facility to read the caret
owner's taskname enables it to be wholly context
sensitive, whereas previous versions simply opened
and closed strips as applications were loaded and
quit.

The <KeyWindow$Flags> system variable and the
'Options' submenu have both been extended to take
account of the new context options. Also, a very
small but perfectly formed bug which has been around
since the first version, and which meant that the
strip didn't resize upon a mode change if it was
closed, has finally been killed, and a very minor
deficiency (not exactly a bug) concerning reopening
the same strip has been corrected from previous
versions.

Version 1.32: This is the first version to sport the
'Compress' option. Such a feature was suggested by
Rob Sherratt and David Pilling; my thanks to them
for their helpful comments. Minor modifications have
been made to the Templates file in order to avoid
scaling problems in certain modes, and Key Window
will now also justify the text intelligently within
the key labels.

A small bug in the Templates file has also now been
fixed: all the key label icons previously had a
button-type of Click/Drag, and these have now been
changed to just Click, because I found that holding
a mouse button down could cause a click to register
twice, which was quite undesirable. The button-type
Click ensures one click only being registered.
The single exception to this modification is the key
label for <CTRL-SHIFT-F12>, which requires the
Double/Click/Drag button type for its safety
precaution feature to work. This safety feature has
also been changed slightly in this version, from a
sort of double-drag-click within the icon to a click
with both SELECT and ADJUST together. This is safer,
more reliable and less temperamental.

The save routine has been slightly modified in this
version to ensure that if automatic F12 labels are
being used, the full label is saved, rather than the
shorter version used in the Compress mode display.

Version 1.40: I'm supposed to be working on Key
Window 2 at this point, but I'm not being able to
find time to get down to it. Therefore I've fixed
the bugs I knew about in version 1.32, and added
some high resolution sprites for RISC OS 3 users. I
also created some icons for use with the Pinboard.
Full help on menus for RISC OS 3 has been added too.

Three small bugs corrected: trying to open a strip
for a task which doesn't have one defined now sounds
a beep rather than flashing a strip on and off the
screen. Defining a 16-character key label no longer
obliterates the label for the next key along. Strips
now take the size of the title bar into account when
different window tools are in use by RISC OS 3. I
also found a fourth problem which I'm sure wasn't
there under RISC OS 2: the checking of files in the
keystrip data directory wasn't working, and so newly
defined keystrips were overwriting existing ones.
Not a happy situation! I've therefore used a better
checking procedure, and the problem has gone away.
I suspect that results from certain OS_File calls
have changed with RISC OS 3, as this area of Key
Window (which used to work) has not, so far as I can
remember, been changed.

Version 1.50: Prior to this version, Key Window used
to interfere with the auto-save document feature in
Impression, preventing it from working. This was due
to the use of a dummy message to follow which task
owned the caret. However, I have discovered how to
do this a better way, and so the dummy message has
now gone (which is good) and the program no longer
upsets any other applications. You can, therefore,
now rely on Impression's auto-save whilst Key Window
is running. This is the most important, but least
visible, change in this version.

A second change is the addition of 3D templates.
In order to use these, you must have (a) RISC OS 31
or later fitted, and (b) have the 'desktop 3D'
option switched on. (This is achieved by setting bit
1 of CMOS RAM byte 140.) There have been a few other
changes to the templates so they work OK with the
new Acorn desktop (with shaded window backgrounds).

Due to some scaling problems with the 3D borders,
the 'compress' options's workings have been modified
slightly, but this should not be noticeable. A small
bug has also been fixed which used to cause the key
label validation strings to sometimes get over-
written; a similar case with the keystrips menu has
also been fixed. I don't think there are any other
bugs left in this version (I hope).

NB There will certainly be a Key Window 2 at some
future point, but finding time to write it is a
major problem. This version (1.50) is therefore a
stop-gap: the new version will have many extra
features, but I don't intend altering Key Window 1
any further now unless I discover any remaining
bugs.

One final point of note is that Key Window is now
supplied with a full 32 keystrips, meaning you can't
add any more without deleting some first. I intend
that Key Window 2 will be able to handle any number
of keystrips (and even have more than one per
application, for applications which directly support
this feature), and they will be stored in a similar
way to fonts in a font directory. Watch this space.

Version 1.51: OK, just one small change, due to a
request. Key Window now uses Wimp_PollIdle to watch
the caret once every second rather than continuously
as before. This makes it a little more sluggish to
change strips (which doesn't really matter), but
reduces the processor-hogging characteristics it has
displayed previously.

Version 1.52: Utterly minuscule changes: removed
colons from the 3D templates' Info window in order
to follow the RISC OS 3 Style Guide, and moved all 4
of these label icons (both templates files) left in
order for them to look better with the new desktop
with outline fonts (otherwise the text looks too
crammed up to the info icons). Also updated the
version number at the very top of this !Help file
(which I'd forgotten to do for version 1.51!).
Thanks to Jack Evans for pointing out some really
stupid mistakes in the !Help file, which I corrected
a few days ago.

Version 1.60: Still not having time to get down to
version 2, I have fixed some stupid bugs which I've
known about for ages and improved things for RISC OS
3.5 on the Risc PC. The most moronic bug was one I
introduced in version 1.51: I completely forgot to
test the program with the 'Compress' option turned
off, until several months after I had released it.
Of course, I found that my changes had made the
scrolling painfully slow. Idiot! This was an easy
fix. There was also a bug which meant that if you
went into a *really* wide screen mode (>1600 pixels)
the 'Compress' option got turned off, and didn't
turn on again when changing back into a smaller
mode.

Other improvements: the error messages now have a
keystrip icon in the error box when used on a Risc
PC, and, much more importantly, the justification of
the text labels in a screen-sized keystrip now take
the desktop outline font into account under RISC OS
3.5, assuming one is in use, of course.

Cosmetic changes: 3D info box resized, red menu
separators made black and 'Options' renamed to
'Choices', all to suit the Style Guide. 'Compress'
option renamed to 'Fit screen', as this is more
accurate. Other small changes to the templates, and
the help file and interactive help messages partly
rewritten. 'Public Domain' renamed to 'Freeware', as
this is what I meant!

Some keystrips for really old programs have been
deleted, and a few new ones added.

Version 1.61: Small bug-fix. In versions of RISC OS
prior to 3.5, tasknames (as appearing in the tasks
window) could only be up to 19 characters long.
From RISC OS 3.5, they can be longer. Key Window
now only checks the first 19 characters of the
taskname, rather than all of it explicitely, and
therefore works correctly on all versions of the
operating system. This was significant for
Impression Publisher, which is 20 characters long.
Luckily, Computer Concepts gave Impression Publisher
Plus the taskname "Publisher Plus"; if they'd called
it "Impression Publisher+", Key Window would not be
able to tell the difference between it and
Impression Publisher!

Corrected a small mistake in the 2D templates.

Thanks to Van Sidwells of Architects-Engineers-
Designers Ltd for prompting me to make the version
1.61 changes, and for supplying a few keystrips.

Version 1.62: Key Window had started crashing
occasionally on a Risc PC, complaining about
illegal window handles and (maybe) not being able
to find the caret's task on occasion. I've no idea
why, but I'm now using the X versions of the
appropriate SWIs to avoid this happening.

Version 1.63: Functionally identical to version 1.62
but now updated for compatibility with the 32-bit
RISC OS 5 as introduced on the Iyonix PC. New icons
added for RISC OS 5 (and a couple for RISC OS 4 for
good measure). Also updated a few of the strip
definitions for consistency, renamed all the strips
(they now use the names of their applications rather
than unhelpful sequential numbers) and reduced the
number activated as standard (as many were for
ancient programs that few people probably use these
days). Supplied the complete set of strips in the
new StripDefs director, including the selection
supplied by Chris Parker.

- R.G.H.
